Sessions

Not available for all users. Contact [email protected] for more information about this endpoint.

Base URL

All following endpoints operate over the URL of your store: https://your-store.com

Example: https://example.publica.la

Endpoints
Retrieve

Headers

{
  "Content-Type": "application/json",
  "Accept": "application/json",
  "X-User-Token": "api_token"
}

info

Make sure you generated the api_token on your store. More info HERE

Retrieve

GET /integration-api/v1/consumption/sessions

Query Parameters

Parameter	Type	Example
cursor	string	/integration-api/v1/consumption/sessions?cursor=eyJzdGF....J1ZX0
issue_id	integer	/integration-api/v1/consumption/sessions?issue_id=1125899910000160
user_id	integer	/integration-api/v1/consumption/sessions?user_id=1125899911002602
reason_type	string	/integration-api/v1/consumption/sessions?reason_type=free_issue
reason_value	integer	/integration-api/v1/consumption/sessions?reason_type=subscription_with_collectionsreason_value=3357
from_date	string	/integration-api/v1/consumption/sessions?from_date=2022-09-21&to_date=2022-09-23
to_date	string	/integration-api/v1/consumption/sessions?to_date=2022-09-23&to_date=2022-09-23

tip

Query parameters can be combined to achieve more specific filtering. All are optional, except the from_date and to_date fields which always go together, just as to send a reason_value you must specify reason_type.

tip

The cursor parameter can be used to paginate results.

Response

Code	Description
200	Success
403	Feature disabled for your store
401	Unauthenticated

Response Example

{
    "CODE": "success",
    "current_page": 1,
    "data": [
        {
            "uuid": "151:8000005:9000886:1734446548",
            "issue_id": 8000005,
            "user_id": 9000886,
            "volpe_host": "farfalla",
            "reason_type": "assigned_issue",
            "reason_value": null,
            "seconds_reading": 125,
            "started_at": "2024-12-17 14:42:28",
            "page_changes": 12,
            "last_heartbeat_at": null,
            "user_email": "[email protected]"
        }
    ],
    "path": "https://example.publica.la/integration-api/v1/consumption/sessions",
    "per_page": 25,
    "next_cursor": "eyJzdGFydGVkX2F0IjoiMjAyNC0wOS0xOCAxNjoxMzoxMCIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
    "next_page_url": "https://example.publica.la/integration-api/v1/consumption/sessions?cursor=eyJzdGFydGVkX2F0IjoiMjAyNC0wOS0xOCAxNjoxMzoxMCIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
    "prev_cursor": null,
    "prev_page_url": null
}

Response Fields

The response is paginated with up to 25 sessions per page. Each session includes the following fields:

Field	Type	Description
uuid	string	Unique identifier for the session, combining tenant_id, issue_id, user_id, and timestamp.
issue_id	integer	ID of the edition associated with the session.
user_id	integer/null	ID of the user in the system. Null for guest.
user_email	string	Email of the user.
volpe_host	string	Platform where the session occurred. Possible values: farfalla, fenice, fenice_desktop.
reason_type	string	Reason the user accessed the content. Possible values are detailed below.
reason_value	integer/null	Additional data related to the reason, such as subscription plan ID for certain types.
started_at	datetime	Timestamp when the session started.
seconds_reading	integer	Duration of the session in seconds.
page_changes	integer	Number of page changes during the session.
last_heartbeat_at	datetime	Timestamp of the last activity ping in the session.

Possible reason_type Values

Value	Description
license_retail	Content accessed through a retail license.
administrator_user	Content accessed by an administrator.
free_issue	Content accessed because it is free.
preview_issue	Content preview access enabled.
free_access	Content accessed via integration with free access enabled.
bought_issue	Content purchased by the user.
assigned_issue	Content assigned manually by an administrator.
gifted_issue	Content gifted to the user.
external_permissions	Access through integration of reading permissions.
subscription_with_collections	Access through a subscription with content collections.
global_subscription	Access through a subscription granting global content access.
lti_and_entry_point_free_access	Access through LTI integration.
saml_and_entry_point_free_access	Access through SAML integration.

In cases where reason_type is subscription_with_collections or global_subscription, reason_value will contain the subscription plan ID.

info

The plan id can be found HERE